home *** CD-ROM | disk | FTP | other *** search
/ Aminet 31 / Aminet 31 (1999)(Schatztruhe)[!][Jun 1999].iso / Aminet / dev / gui / gtlayout.lha / Source / LT_Build.c < prev    next >
C/C++ Source or Header  |  1998-09-09  |  29KB  |  1,182 lines
  1. /*
  2. **    GadTools layout toolkit
  3. **
  4. **    Copyright © 1993-1998 by Olaf `Olsen' Barthel
  5. **        Freely distributable.
  6. **
  7. **    :ts=4
  8. */
  9.  
  10. #ifndef _GTLAYOUT_GLOBAL_H
  11. #include "gtlayout_global.h"
  12. #endif
  13.  
  14. /*****************************************************************************/
  15.  
  16. #include <stdarg.h>
  17.  
  18. /*****************************************************************************/
  19.  
  20. #include "Assert.h"
  21.  
  22. /*****************************************************************************/
  23.  
  24. /****** gtlayout.library/LT_BuildA ******************************************
  25. *
  26. *   NAME
  27. *    LT_BuildA -- turn the user interface specs into a window
  28. *                 and gadgets.
  29. *
  30. *   SYNOPSIS
  31. *    Window = LT_BuildA(Handle,Tags);
  32. *      D0                 A0    A1
  33. *
  34. *    struct Window *LT_BuildA(LayoutHandle *,struct TagItem *);
  35. *
  36. *    Window = LT_Build(Handle,...);
  37. *
  38. *    struct Window *LT_Build(LayoutHandle *,...);
  39. *
  40. *   FUNCTION
  41. *    This is the big one. After building up a user interface specification
  42. *    using LT_NewA() a call to LT_BuildA() will finally lay out the single
  43. *    user interface elements, open a window and put the gadgets, etc.
  44. *    inside.
  45. *
  46. *    The code tries to fit all the gadgets into the window, but if it
  47. *    runs out of space it will fall back to a different font and
  48. *    rescale the user interface objects to match it. It will first
  49. *    fall back onto the system default font. If unsuccessful it will
  50. *    as a last resort try to use topaz.font/8.
  51. *
  52. *    To make it easier to distinguish between different handles that
  53. *    share the same Window->UserPort, the Window->UserData pointer
  54. *    will point to the LayoutHandle that created it (V13).
  55. *
  56. *        NOTE: Earlier library releases did not support this feature,
  57. *            so be prepared to deal with Window->UserData == NULL.
  58. *
  59. *   INPUTS
  60. *    Handle - Pointer to a LayoutHandle structure.
  61. *
  62. *    Tags - Pointer to TagItem list controlling window
  63. *        and layout attributes.
  64. *
  65. *
  66. *    All the tag values given are passed straight away to OpenWindowTags(),
  67. *    see intuition.doc for more information.
  68. *
  69. *    In addition to this a number of private tag values are supported:
  70. *
  71. *    LAWN_Menu (struct Menu *) - The menu to attach to the window. The
  72. *        IDCMP flags will be updated to include IDCMP_MENUPICK if this
  73. *        tag is used.
  74. *
  75. *    LAWN_MenuTemplate (struct NewMenu *) - A list of filled-in
  76. *        NewMenu structures which will get passed straight through
  77. *        to LT_NewMenuTemplate(). If a menu could be created, it will
  78. *        be attached to the window. LT_DeleteHandle() will then later
  79. *        automatically dispose of the menu. Please note that the window
  80. *        may fail to open due to the menu layout going wrong. Separate
  81. *        calls to LT_NewMenuTemplate() and LT_Build() may be a better
  82. *        approach since it is easier to find out which process went
  83. *        wrong. You will find a pointer to the menu attached to the
  84. *        LayoutHandle in LayoutHandle->Menu. Please note that this
  85. *        entry only exists in LayoutHandles created by gtlayout.library
  86. *        v13 or higher. (V13)
  87. *
  88. *            NOTE: This tag effectively overrides LAWN_Menu.
  89. *
  90. *    LAWN_MenuTags (struct TagItem *) - A list of TagItems which
  91. *        will get passed straight through to LT_NewMenuTagList().
  92. *        Even if you don't ask for it, LT_Build() will pass
  93. *        "LAMN_Handle,<Handle>" in for you, so any additional tags
  94. *        specifying screen, fonts, etc. will be overridden. If a menu
  95. *        could be created, it will be attached to the window.
  96. *        LT_DeleteHandle() will then later automatically dispose of the
  97. *        menu. Please note that the window may fail to open due to the
  98. *        menu layout going wrong. Separate calls to LT_NewMenuTagList()
  99. *        and LT_Build() may be a better approach since it is easier to
  100. *        find out which process went wrong. You will find a pointer to the
  101. *        menu attached to the LayoutHandle in LayoutHandle->Menu. Please note
  102. *        that this entry only exists in LayoutHandles created by
  103. *        gtlayout.library v13 or higher. (V13)
  104. *
  105. *            NOTE: This tag effectively overrides LAWN_Menu and has
  106. *                  precedence over LAWN_MenuTemplate.
  107. *
  108. *    LAWN_UserPort (struct MsgPort *) - The MsgPort to use as the
  109. *        window user port. The MsgPort will be attached using the
  110. *        common ModifyIDCMP() method, closing the window will
  111. *        first remove and reply all pending messages at this port.
  112. *
  113. *    LAWN_Left (LONG) - The left edge position the window is to use.
  114. *        This effectively overrides any horizontal alignment flags.
  115. *
  116. *            NOTE: the code may choose to ignore this value if it finds
  117. *                that the window will not fit onto the screen unless
  118. *                the left edge position is changed.
  119. *
  120. *    LAWN_Top (LONG) - The top edge position the window is to use.
  121. *        This effectively overrides any vertical alignment flags.
  122. *
  123. *            NOTE: the code may choose to ignore this value if it finds
  124. *                that the window will not fit onto the screen unless
  125. *                the top edge position is changed.
  126. *
  127. *    LAWN_Zoom (BOOL) - Adds a zoom gadget to the window. Clicking
  128. *        on this gadget will cause the window to shrink/zoom back
  129. *        to its original position. This differs from the WA_Zoom
  130. *        tag behaviour. When the window zooms back to its original
  131. *        position the gadgets are automatically refreshed.
  132. *        Default: FALSE
  133. *
  134. *    LAWN_MaxPen (LONG) - The maximum rendering pen index your code
  135. *        will use. Since you are -- with some restrictions -- allowed
  136. *        to render into the window created you may want to avoid
  137. *        silly side effects if drawing images or other colourful
  138. *        textures which do not share the common user interface colours.
  139. *        By default the layout code will change the maximum rendering
  140. *        pen number for the window to include only the user interface
  141. *        pen colours. This can, but need not disturb your own private
  142. *        window rendering.
  143. *        Look up graphics.library/SetMaxPen for more information.
  144. *        Default: determined by looking up Screen->DrawInfo.dri_Pens
  145. *
  146. *    LAWN_BelowMouse (BOOL) - This instructs the layout routine to
  147. *        centre the window created -- if possible -- below the
  148. *        mouse pointer. This effectively ignores any left edge,
  149. *        top edge or alignment settings.
  150. *        Default: FALSE
  151. *
  152. *    LAWN_MoveToWindow (BOOL) - When the window is finally open the
  153. *        user interface code will try to make sure the entire window
  154. *        is visible on the screen, this may involve moving the
  155. *        currently visible portion of an autoscrolling screen.
  156. *        Default: TRUE
  157. *
  158. *    LAWN_AutoRefresh (BOOL) - Handle IDCMP_REFRESHWINDOW events
  159. *        automatically.
  160. *        Default: TRUE
  161. *
  162. *    LAWN_HelpHook (struct Hook *) - Hook code to invoke when the user
  163. *        presses the "Help" key. See gtlayout.h for more information.
  164. *        Default: NULL
  165. *
  166. *    LAWN_Parent (struct Window *) - Parent window to centre the child
  167. *        window in.
  168. *        Default: NULL
  169. *
  170. *    LAWN_BlockParent (BOOL) - Lock the parent window via LT_LockWindow()
  171. *        until the child window is closed.
  172. *
  173. *            NOTE: requires LAWN_Parent attribute.
  174. *
  175. *        Default: FALSE
  176. *
  177. *    LAWN_SmartZoom (BOOL) - Attach a zoom gadget to the window created.
  178. *        When in zoomed state, the window will be as small as possible,
  179. *        showing only the window title and window gadgets:
  180. *
  181. *            NOTE: this tag implies LAWN_Zoom,TRUE
  182. *
  183. *        Default: FALSE
  184. *
  185. *    LAWN_Title (STRPTR) - The window title to use. Use this tag in
  186. *        place of WA_Title or you will break the layout code.
  187. *        Default: no title
  188. *
  189. *    LAWN_Bounds (struct IBox *) - Bounds to centre the window in.
  190. *        Default: NULL
  191. *
  192. *    LAWN_ExtraWidth (LONG) - Extra width to add into the calculation
  193. *        when opening the window.
  194. *        Default: 0
  195. *
  196. *    LAWN_ExtraHeight (LONG) - Extra height to add into the calculation
  197. *        when opening the window.
  198. *        Default: 0
  199. *
  200. *    LAWN_IDCMP (ULONG) - Use this tag in place of WA_IDCMP or you
  201. *        will break the object handling code.
  202. *
  203. *    LAWN_AlignWindow (UWORD) - Alignment information for the window, must
  204. *        be a mask made from the following bit values:
  205. *
  206. *            ALIGNF_RIGHT - Align to screen right edge
  207. *            ALIGNF_LEFT - Align to screen left edge
  208. *            ALIGNF_TOP - Align to screen top edge
  209. *            ALIGNF_BOTTOM - Al